mask#

The mask modifier clips the visual rendering of a view using the alpha channel of another view. Only the parts of the original view that align with the opaque (non-transparent) portions of the mask remain visible; the rest is hidden.

This is commonly used to apply custom shapes, spotlight effects, or partial reveals.

Type#

1mask?: VirtualNode | {
2  alignment: Alignment
3  content: VirtualNode
4}

Usage#

1. Simple Form#

Apply a mask view directly. The mask is centered on the base view by default.

1<Image
2  filePath="path/to/photo.png"
3  frame={{ width: 100, height: 100 }}
4  mask={<Circle />}
5 />

In this example, the image is clipped to a circular shape using a Circle as the mask. Only the circular portion of the image is visible.

2. Object Form (with Alignment)#

Use this form when you want to position the mask relative to the base view.

Structure:#

1{
2  alignment: Alignment
3  content: VirtualNode
4}

Alignment values:#

• "top" | "bottom" | "leading" | "trailing"
• "topLeading" | "topTrailing" | "bottomLeading" | "bottomTrailing"
• "center"

Example – apply a top-aligned rectangular mask:#

1<Rectangle
2  fill="blue"
3  frame={{ width: 100, height: 100 }}
4  mask={{
5    alignment: "top",
6    content: <Rectangle frame={{ width: 100, height: 50 }} />
7  }}
8/>

Only the top half of the blue rectangle will be visible, defined by the opaque rectangle used as the mask.

Behavior#

• The mask view’s opacity determines the visibility of the base view.

  • Opaque areas (alpha = 1) show the base view.
  • Transparent areas (alpha = 0) hide it.

• The mask does not affect layout, only how the content is rendered.

• Use frame={{ width, height }} on both base and mask views to ensure proper alignment and coverage.

Common Use Cases#

• Cropping images into non-rectangular shapes (e.g., circle, capsule)
• Creating spotlight or reveal effects
• Masking decorative or semantic content

Summary#